{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Getting started and authenticating\n",
    " Run this code to authenticate.Gs_quant requires to be initialized session with your credentials. Provide 'client_id' and 'client_secret' to session initializer. If you see an error, please e-mail the error message to gs-marquee-help@gs.com.."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "import datetime\n",
    "import json\n",
    "\n",
    "from gs_quant.target.secmaster import SecMasterAssetType, SecMasterIdentifiers\n",
    "from gs_quant.api.gs.secmaster import GsSecurityMasterApi\n",
    "from gs_quant.markets.securities import SecurityIdentifier\n",
    "from gs_quant.session import GsSession\n",
    "import pandas as pd\n",
    "GsSession.use(client_id=\"\",\n",
    "              client_secret=\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Pagination\n",
    "Whenever you encounter an `offsetKey` in the response it means that results did not fit the page size, and this requires a more requests to get all data.\n",
    "\n",
    "Initial call that  returns first `offsetKey`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results  = GsSecurityMasterApi.get_many_securities(type_=SecMasterAssetType.Common_Stock, limit=500)\n",
    "offset_key = results['offsetKey']\n",
    "print(f\"Offset key is {offset_key}\")\n",
    "pd.DataFrame(results['results'][-5:])[[\"id\", \"name\", \"currency\", \"assetClass\", \"type\", \"effectiveDate\"]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Subsequent call using last `offsetKey` for next call. It returns next page of  data. This pattern can be applied to all instances where `offsetKey` is returned"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results  = GsSecurityMasterApi.get_many_securities(type_=SecMasterAssetType.Common_Stock, limit=10, offset_key=offset_key)\n",
    "offset_key = results['offsetKey']\n",
    "print(f\"New offset key is {offset_key}\")\n",
    "pd.DataFrame(results['results'][-5:])[[\"id\", \"name\", \"currency\", \"assetClass\", \"type\", \"effectiveDate\"]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Securities\n",
    "The Securities section is the analytical core of the service, focusing on providing asset-specific data. It is designed for users who require detailed information about individual securities, need to trace the history and changes of security identifiers, or wish to obtain bulk security data by asset type.\n",
    "\n",
    "#### Historical query\n",
    "\n",
    "The historical query functionality is tailored for users requiring time-specific data retrieval. It allows you to perform a point-in-time query by specifying an identifier (e.g. bbid) and a precise date. This can be important for tasks such as data verification, back-testing models against historical data.\n",
    "It effectively enables you to 'query back in time', providing a snapshot of security's data as it existed at that exact moment"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "data = GsSecurityMasterApi.get_security_data(id_value=\"META UW\", id_type=SecurityIdentifier.BBID,\n",
    "                                             effective_date=datetime.date(2024, 10, 28))\n",
    "print( f\"The bbid is: {data['identifiers.bbid']} and the issuer name is: {data['issuer.name']}.\")  # Prints bbid and company name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "#### Query by identifier\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "This functionality allows you to immediate access to current data on specific security. By inputting an identifier, users can quickly retrieve the latest available information about the security"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "\n",
    "data = GsSecurityMasterApi.get_security_data(id_value=\"GS UN\", id_type=SecurityIdentifier.BBID)\n",
    "print( f\"The bbid is: {data['identifiers.bbid']} and the issuer name is: {data['issuer.name']}.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "#### Query by attribute\n",
    "\n",
    "This functionality is a versatile tool for customized queries. Users can specify an asset type, or set of identifiers to retrieve matching securities. This function accepts multiple identifiers, either individually or in batch, enabling a broad or targeted browse.\n",
    "It is particular useful for users how need to extract a specific subset of data from a vast pool of securities, aligning with particular investment strategies, or research parameters.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "etf  = GsSecurityMasterApi.get_many_securities(type_=SecMasterAssetType.ETF, limit=5)\n",
    "[ print( f\"The bbid is: {data['identifiers']['bbid']} and the issuer name is: {data['issuer']['name']}.\") for data in etf[\"results\"]]\n",
    "print(\"-\"*80)\n",
    "single_asset = GsSecurityMasterApi.get_many_securities(bbid=\"IZB PW\")\n",
    "[ print( f\"The bbid is: {data['identifiers']['bbid']} and the issuer name is: {data['issuer']['name']}.\") for data in single_asset[\"results\"]]\n",
    "print(\"-\"*80)\n",
    "many_assets = GsSecurityMasterApi.get_many_securities(ric=[\"GOOGL.OQ\", \"VOD.L\"])\n",
    "[ print( f\"The bbid is: {data['identifiers']['bbid']} and the issuer name is: {data['issuer']['name']}.\") for data in many_assets[\"results\"]]\n",
    "print(\"-\"*80)\n",
    "ticker = GsSecurityMasterApi.get_many_securities(ticker=\"GS\")\n",
    "[ print( f\"The name is: {data['name']} and the issuer name is: {data['issuer']['name']}.\") for data in ticker[\"results\"]]\n",
    "print(\"-\"*80)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "#### Get all securities\n",
    "This acts as an expansive layer over 'Query by Attribute', tailored for retrieving an extensive list of assets within a specific type, It simplifies the user experience by automatically handling the scrolling, thereby providing a seamless method to acquire a complete dataset of a chosen asset type.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "data = GsSecurityMasterApi.get_all_securities(type_=SecMasterAssetType.Dutch_Cert)\n",
    "print(json.dumps(data['results'][0:60], indent=4))  # Prints prettified response\n"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "**NOTE** Not all functionalities are available for Base Tier."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "#### Get identifier history\n",
    "The 'Get identifier history' functionality is designed to provide a chronological account of how a particular identifier has changed for a security over time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "secm_id = \"GSPD227284E154\"\n",
    "data = GsSecurityMasterApi.get_identifiers(secmaster_id=secm_id)\n",
    "pd.DataFrame(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "#### Map securities\n",
    "\n",
    "This functionality is a powerful tool for converting between different types of security identifiers while also taking historical changes int account. Users can input a security's identifier alon with its type (e.g, bbid, sedol) and specify  the desired output identifier types. This function then returns a mapping of the security across these different identifier systems."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "mapping = GsSecurityMasterApi.map(SecurityIdentifier.BBID, [\"GS UN\"], start_date=\"2015-01-01\", end_date=\"2020-01-01\",\n",
    "                                  output_types=[SecurityIdentifier.TICKER, SecurityIdentifier.RIC])\n",
    "pd.DataFrame(mapping)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Search securities\n",
    "\n",
    "This functionality is a designed for conducting full-text searches across many fields, including identifiers, company names. This is especially beneficial for users who require a more exploratory approach to data retrieval.\n",
    "\n",
    "This supports also filtering options, where users can refine their search results using filters such as 'isPrimary', 'activeListing' and restrict searches to selected asset type. This helps narrow down the results\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Plain full text search query:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results = GsSecurityMasterApi.search(q=\"TESLA\")\n",
    "[\n",
    "    f\"The bbid is: {data['identifiers']['bbid']} and the issuer name is: {data['issuer']['name']} and the type is: {data['type']}.\"\n",
    "    for data in results\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Full text query with filters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results = GsSecurityMasterApi.search(q=\"TESLA\", is_primary=True, active_listing=True, type_=SecMasterAssetType.Common_Stock)\n",
    "[\n",
    "    f\"The bbid is: {data['identifiers']['bbid']} and the issuer name is: {data['issuer']['name']}  and the type is: {data['type']}.\"\n",
    "    for data in results\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "#### Get recent changes\n",
    "You can get the list of recent identifier changes by providing between start/end time. The start/end time are limited to span of 5 days and should not start more than 30 days from now\n",
    "The API allows returning processed results highlighting the change nature (easier to interprate), or raw results easier to process programmatically"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Raw results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "start_time = datetime.datetime.now() - datetime.timedelta(hours=12)\n",
    "data = GsSecurityMasterApi.get_deltas(raw=True, start_time=start_time)\n",
    "pd.DataFrame(data['results'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Processed results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "start_time = datetime.datetime.now() - datetime.timedelta(hours=12)\n",
    "data = GsSecurityMasterApi.get_deltas(raw=False, start_time=start_time)\n",
    "sample = json.dumps(data['results'][:10], indent=4)\n",
    "print(sample)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Corporates\n",
    "\n",
    "Secmaster service allows providing a detailed insights into financial structure and activities of listed companies."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Capital Structure\n",
    "\n",
    "This functionality is a tool for gaining a comprehensive understanding of different types of securities issued by a company. By utilizing various identifiers, users can pinpoint a specific company and retrieve a detailed list of its issued securities, including bonds, stocks and other.\n",
    "It supports point-in-time query."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Markdown\n",
    "ric = \"VOD.L\"\n",
    "data = GsSecurityMasterApi.get_capital_structure(id_value=ric, id_type=SecurityIdentifier.RIC)\n",
    "res = data['results'][0]\n",
    "display(Markdown(f\"Capital structure for {ric} matched {res['issuerName']}\"))\n",
    "display(pd.DataFrame([data['assetTypesTotal']]))\n",
    "for t in res['types']:\n",
    "    display(Markdown(f\"**{t}**\"))\n",
    "    display(pd.DataFrame(res['types'][t][:5]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Corporate Actions\n",
    "\n",
    "This functionality provides the ability to track both historical na upcoming corporate actions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "corp = GsSecurityMasterApi.get_corporate_actions(id_value=\"227284\")\n",
    "pd.DataFrame(corp)[[\"corpActionId\", \"eventId\", \"eventType\", \"eventStatus\", \"gsid\", \"effectiveDate\", \"announceDate\", \"multiplicativeAdjust\", \"additiveAdjust\"]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exchanges\n",
    "\n",
    "You can fetch data about exchanges. The API allows either fetching all exchanges or query by exchange identifier"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###  Get  many exchanges\n",
    "This functionally allows users to retrieve detailed information about exchanges. User can fetch all exchanges or query by selected identifiers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = GsSecurityMasterApi.get_exchanges()\n",
    "pd.DataFrame(data['results'][:5])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###  Query exchanges by identifiers\n",
    "\n",
    "data = GsSecurityMasterApi.get_exchanges(mic=\"XBUE\")\n",
    "pd.DataFrame(data['results'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = GsSecurityMasterApi.get_exchanges(mic=\"XBUE\")\n",
    "pd.DataFrame(data['results'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get exchanges identifiers history\n",
    "\n",
    "This functionality is designed to provide a historical view of the changes in exchange identifiers over time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results = GsSecurityMasterApi.get_exchange_identifiers_history(gs_exchange_id=1)\n",
    "pd.DataFrame(results)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
